Summary

Adds a CLAUDE.md file — a structured architecture guide that AI coding assistants (Claude Code, Copilot, Cursor, etc.) automatically read when working on this repository.

Why CLAUDE.md?

Golbat has significant architectural complexity that isn't obvious from reading individual files:

• The two-level spatial query pattern (R-tree + lookup cache) that avoids entity locks during scans — a developer unfamiliar with this could easily introduce lock contention by querying entities directly in a scan loop
• Four distinct record access patterns (Peek, ReadOnly, ForUpdate, GetOrCreate) with different snapshotting and DB fallback behavior — using the wrong one causes subtle bugs (missing webhook diffs, unnecessary DB hits, deadlocks)
• Write-behind queue coalescing with pokemon delay — understanding why wild pokemon have a 30s write delay is essential context for anyone touching the save path
• Lock ordering constraints — the pokestop↔gym conversion pattern requires releasing one lock before acquiring another, which isn't self-documenting
• Fort tracker stale detection — the S2 cell-based lifecycle tracking has non-obvious interactions with the cache eviction and R-tree systems

Without this context, contributors (human or AI) tend to:

1. Re-lock entities that are already locked, causing deadlocks
2. Use ReadOnly when ForUpdate is needed, losing webhook change detection
3. Query full entities inside scan loops instead of using the lookup cache
4. Miss the implications of the pokemon write delay when debugging data freshness issues

The guide covers: raw message processing pipeline, entity model patterns, caching (sharded vs TTL), locking model, write-behind queues, webhooks, fort tracking, and the R-tree/DNF spatial query system.

Test plan

• Verified accuracy against current codebase
• Review by maintainers for any inaccuracies or missing context

🤖 Generated with Claude Code